dxp-ux
GET PaymentHistory (TMF-676)
listPayment
This operation retrieves the payment history by using account number.
This operation is towards
- LCPR: Aria, Matrixx, CSG.
- Panama: Liberate
Request URL
https://[localhost]:[port]/dxp-ux/v1/{businessId}/paymentURL PARAMS
| name | type | description | required |
|---|---|---|---|
| businessId | string | 2 letter ISO 3166 country code (TT, BB, JM, PA, etc.) identifying the business unit. | Y |
Header
| name | value | description | required (mandatory-Y, optional-N, Not applicable- N/A) |
|---|---|---|---|
| client_id | string | The client_id identifying the channel. Minimum characters: 5 | Y(PR, PA) |
| client_secret | string | Password associated with the client_id. Minimum characters: 5 | Y(PR, PA) |
| X-Correlation-ID | string | Identifier that correlates HTTP request between a client and server. Any identification model (UUDI, checksum, etc.) can be used, as long as it is a unique value to differentiate a transaction. | N(PR, PA) |
| channelId | string | Channel to business Allowed Value : APP | Y(PR) N/A(PA) |
| lob | string | The Line of Business Identifier Allowed ENUM values: FIXED, PREPAID, POSTPAID | Y (PR. For Matrixx not in scope) N/A(PA) |
| targetSystem | string | Expected target system: csg, matrixx, aria | Y (PR) N/A(PA) |
Query Param
| name | type | description | required (mandatory-Y, optional-N, Not applicable- N/A) |
|---|---|---|---|
| account_no | string | To retrieve the payments from a specific account | Y(PR, PA) |
| startDate | string | To retrieve the payments performed after this date | N(PR, PA) |
| endDate | string | To retrieve the payments performed before this date | N(PR, PA) |
| paymentItem.referredType | string | To retrieve the payments from a specific referredType Possible values are: history, planDetails, plansByAcct, receipt, deposits, depositDetails, items, summary | N/A(PR) N(PA) |
Data Model
Response Data Model
| name | type | description | required (mandatory-Y, optional-N, Not applicable- N/A) |
|---|---|---|---|
| id | string | Unique identifier of Payment | Y(PR, PA) |
| description | string | Text describing the contents of the payment | N(PR) Y(PA) |
| correlatorId | string | Unique identifier in the client for the payment in case it is needed to correlate | N(PR) Y(PA) |
| status | string | Status of the payment | N(PR) Y(PA) |
| statusDate | datetime or string | Date when the status was recorded Note for PA: This field type is string | N(PR) Y(PA) |
| name | string | Screen name of the payment | N(PR) Y(PA) |
| paymentDate | datetime or string | Date when the payment was performed Note for PA: This field type is string | N(PR) Y(PA) |
| extendedCharacteristics[] | array | Represents additional attributes of payment entity | N(PR) N/A(PA) |
| extendedCharacteristics[].name | string | name of the additional attributes (ex: "paymentDate", "procStatusCode") | N(PR) N/A(PA) |
| extendedCharacteristics[].value | string | value of the additional attributes(ex: "2023-06-09", 100) | N(PR) N/A(PA) |
| account | object | Account reference. A account may be a party account or a financial account. | N(PR) Y(PA) |
| account.id | string | Unique identifier of the account | N(PR) Y(PA) |
| account.@type | string | When sub-classing, this defines the sub-class entity name | N(PR) N/A(PA) |
| account.name | string | Name of the account | N(PR) Y(PA) |
| account.description | string | Detailed description of the account | N/A(PR) Y(PA) |
| amount | object | A base / value business entity used to represent money | N(PR) N/A(PA) |
| amount.value | number | A positive floating point number | N(PR) N/A(PA) |
| amount.unit | string | Currency (ISO4217 norm uses 3 letters to define the currency) | N(PR) N/A(PA) |
| amount.amount | number | A positive floating point number | N(PR) N/A(PA) |
| paymentMethod | object | link to the resource that holds information about the payment mean used to complete the operation | Y(PR, PA ) |
| paymentMethod.id | string | Unique Identifier within the server for the payment method. | N(PR) N/A(PA) |
| paymentMethod.@type | string | When sub-classing, this defines the sub-class entity name | N(PR) Y(PA) |
| paymentMethod.details | object | Details of payment method | N(PR) N/A(PA) |
| paymentMethod.details.type | string | Type of payment method | N(PR) N/A(PA) |
| paymentMethod.details.cardNumber | string | Card Number | N(PR) N/A(PA) |
| paymentMethod.details.expirationDate | string | Card Expiry Date | N(PR) N/A(PA) |
| paymentItem[] | array | The paymentItem is the result of lettering process. It enables to assign automatically or manually part of incoming payment amount to a bill | N(PR) Y(PA) |
| paymentItem[].totalAmount | object | A base / value business entity used to represent money | N(PR) Y(PA) |
| paymentItem[].totalAmount.amount | number | A positive floating point number | N(PR) N/A(PA) |
| paymentItem[].totalAmount.value | number | A positive floating point number | N/A(PR) Y(PA) |
| paymentItem[].item | object | Entity reference schema to be use for all entityRef class. | N(PR) Y(PA) |
| paymentItem[].item.id | string | Unique identifier of a related entity. | N(PR) N/A(PA) |
| paymentItem[].item.referredType | string | The actual type of the target instance when needed for disambiguation. | N(PR) N/A(PA) |
| paymentItem[].item.@referredType | string | The actual type of the target instance when needed for disambiguation. | N/A(PR) Y(PA) |
| item | object | Reference where to get more information about the entity with another API call | N(PR) N/A(PA) |
| item.referredType | string | The actual type of the target instance when needed for disambiguation. | N(PR) N/A(PA) |
| item.id | string | Unique identifier of a related entity. | N(PR) N/A(PA) |
| refund[] | array | array for the refund details | N(PR) N/A(PA) |
| refund[].id | string | Refunded id (unique) from matrixx | N(PR) N/A(PA) |
| refund[].totalAmount | object | refund amount details | N(PR) N/A(PA) |
| refund[].totalAmount.value | number | refund amount value | N(PR) N/A(PA) |
| refund[].totalAmount.unit | string | Currency (ISO4217 norm uses 3 letters to define the currency) | N(PR) N/A(PA) |
| refund[].status | string | staus of the refund(ex: refunded) | N(PR) N/A(PA) |
| refund[].refundDate | datetime | Date of the refund | N(PR) N/A(PA) |
| refund[].@type | string | When sub-classing, this defines the sub-class entity name(ex: "RefundRef") | N(PR) N/A(PA) |
| totalAmount | object | A base / value business entity used to represent money | N(PR) Y(PA) |
| totalAmount.value | number | A positive floating point number | N(PR) Y(PA) |
| totalAmount.unit | string | Currency (ISO4217 norm uses 3 letters to define the currency) | N(PR) N/A(PA) |
| totalAmount.amount | number | A positive floating point number | N(PR) N/A(PA) |
| taxAmount | object | A base / value business entity used to represent money | N(PR) N/A(PA) |
| taxAmount.amount | number | A positive floating point number | N(PR) N/A(PA) |
| @type | string | When sub-classing, this defines the sub-class entity name | N(PR) N/A(PA) |
paymentItem subResource - dataModel
| resource characteristic name | type | description | required(mandatory-Y, optional-N, Not applicable- N/A) | examples |
|---|---|---|---|---|
| payment | string | The actual type of the target instance when needed for disambiguation. | Y(PA) | PA: { "item": { "referredType": "payment"}} |
| deposit | string | The actual type of the target instance when needed for disambiguation. | Y(PA) | PA: {"item": { "referredType": "deposit"}} |
extendedCharacteristics subResource - dataModel
| resource characteristic name | type | description | required(mandatory-Y, optional-N, Not applicable- N/A) | examples |
|---|---|---|---|---|
| procStatusCode | string | Response code from payment processor (Braintree). Possible Values will be :1000(Approved), 4001(settlement_declined), 4000(settled), 81706(CVV is required), ARIA COMM 1 (voided payment), etc... | N(PR) N/A(PA) | PR: { "name": "procStatusCode", "value": "1000" } |
| paymentDate | string | Processor payment date | N(PR) N/A(PA) | PR: { "name": "paymentDate", "value": "2024-02-13" } |
| procPaymentId | string | The processor payment ID | N(PR) N/A(PA) | PR: { "name": "procPaymentId", "value": "bkh04029" } |
| paymentMethodNo | string | Processor payment method number | N(PR) N/A(PA) | PR: { "name": "paymentMethodNo", "value": "1" } |
| procStatusText | string | Payment processor status text is returned The possible payment status is either 'Approved or settled or Settlement Pending or External Payment or Cash Credit or Insufficient Funds or fail or {Unknown} | N(PR) N/A(PA) | PR: { "name": "procStatusText", "value": "Approved" } |
Key considerations
- Please find the responses in following URL: DXP UX : PaymentHistory
PA Implementation
1. This implementation retrieves the payment history for FIXED, POSTPAID accounts.
2. To retrieve payment history for a specific duration, startDate and endDate queryParameters must be passed.
3. If the dates are not specified in queryParams, the API returns history of last one year by default.
4. Description field provides the billReferenceNumber.
5. statusDate field is the enteredDate in Liberate.
6. name field gives the name value which is sent during creating the payment (ThirdPartySource).
7. correlatorId field gives the correlatorId value which is sent during creating the payment (ThirdPartyPaymNo).
8. status possible values are "Returned" or "Success".
9. By default, payment history is retrieved if 'paymentItem.referredType' queryParam is not provided; if specified, it must be sent as "history"
10. For all the dateTime fields
- Any datetime before 1908-04-22 will show offset -05:18
- Any datetime on or after 1908-04-22 will show offset -05:00